CLI Provider

Command-line interface implementation for UTCP

The CLI provider enables UTCP to interact with local command-line tools and utilities, allowing AI agents to leverage existing command-line interfaces without requiring API wrappers. This bridges the gap between modern AI agents and traditional command-line utilities.

Configuration

CLI providers are configured using the following JSON structure:

{
  "name": "my_cli_tool",
  "provider_type": "cli",
  "command_name": "my-command",
  "working_dir": "/path/to/data",
  "param_style": "named",
  "output_format": "json",
  "timeout": 30000,
  "env_vars": {
    "MY_VAR": "some_value",
    "DEBUG": "1"
  }
}

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier for the provider
`provider_type`	Yes	Must be set to `"cli"`
`command_name`	Yes	Name of the CLI command to execute
`working_dir`	No	The working directory from which to run the command
`param_style`	No	How to pass parameters to the command (default: `"named"`)
`output_format`	No	Expected output format (default: `"json"`)
`timeout`	No	Command timeout in milliseconds (default: `30000`)
`env_vars`	No	A dictionary of environment variables to set for the command's execution context

Parameter Styles

CLI tools can receive parameters in several ways, specified by the param_style field:

Style	Description	Example
`named`	Parameters as named options (--name value)	`my-command --input file.txt --format json`
`positional`	Parameters as positional arguments	`my-command file.txt json`
`json`	Parameters as a JSON string in a single argument	`my-command '{"input": "file.txt", "format": "json"}'`
`json_stdin`	Parameters as JSON sent to the command's standard input	`echo '{"input": "file.txt"}' \| my-command`

Output Formats

CLI tools can output results in various formats:

Format	Description
`json`	Command outputs JSON that can be directly parsed
`text`	Command outputs plain text that needs custom parsing
`csv`	Command outputs CSV data that will be parsed into an array
`xml`	Command outputs XML that will be parsed into a JSON structure

Tool Discovery

CLI tools can expose their UTCP tool definitions in two ways:

1. Discovery Flag

The CLI tool accepts a special flag (e.g., --utcp-info) that outputs tool definitions:

$ my-command --utcp-info
{
  "version": "1.0",
  "tools": [
    {
      "name": "convert",
      "description": "Convert between file formats",
      "inputs": { ... },
      "outputs": { ... }
    }
  ]
}

2. Static Definition

Tool definitions are provided in the provider configuration:

{
  "name": "my_cli_tool",
  "provider_type": "cli",
  "command_name": "my-command",
  "tools": [
    {
      "name": "convert",
      "description": "Convert between file formats",
      "inputs": { ... },
      "outputs": { ... }
    }
  ]
}

Examples

Simple File Converter

{
  "name": "file_converter",
  "provider_type": "cli",
  "command_name": "convert",
  "param_style": "named",
  "output_format": "json",
  "timeout": 60000
}

Data Processing Tool

{
  "name": "data_processor",
  "provider_type": "cli",
  "command_name": "process-data",
  "param_style": "json_stdin",
  "output_format": "json",
  "working_dir": "/path/to/data",
  "timeout": 120000,
  "env_vars": {
    "PYTHONPATH": "/custom/python/path",
    "DEBUG": "1"
  }
}

System Administration Tool

{
  "name": "system_monitor",
  "provider_type": "cli",
  "command_name": "monitor",
  "param_style": "positional",
  "output_format": "csv",
  "timeout": 10000,
  "env_vars": {
    "PATH": "/usr/local/bin:/usr/bin:/bin"
  }
}

Security Considerations

Important Security Warning

CLI providers execute commands on the local system, which presents significant security risks if not properly managed. Always implement proper security measures.

Input Validation

• Strictly validate all parameters against schemas
• Sanitize file paths to prevent directory traversal
• Escape arguments to prevent injection attacks

Execution Safety

• Run commands with minimum necessary permissions
• Implement timeouts and resource constraints
• Log command executions for audit trails

Best Practices

Output Handling

• Prefer CLI tools that output structured data
• Capture and parse stderr for error messages
• Implement result caching when appropriate

Performance

• Use asynchronous execution for long-running commands
• Set appropriate timeouts for different operations
• Monitor resource usage and implement limits